home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 23 / AACD 23.iso / AACD / Magazine / PC2Amiga / Samba / docs / textdocs / SSLeay.txt < prev    next >
Text File  |  2000-04-25  |  19KB  |  393 lines
  1. !==
  2. !== SSLeay.txt for Samba release 2.0.7 26 Apr 2000
  3. !==
  4. Contributor: Christian Starkjohann <cs@obdev.at>
  5. Date:        May 29, 1998
  6. Status:      
  7.  
  8. Subject:     Compiling and using samba with SSL support
  9. ============================================================================
  10.  
  11. What is SSL and SSLeay?
  12. =======================
  13. SSL (Secure Socket Layer) is a protocol for encrypted and authenticated data
  14. transport. It is used by secure web servers for shopping malls, telebanking
  15. and things like that.
  16.  
  17. SSLeay is a free implementation of the SSL protocol. It is available from
  18.  
  19.     ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/
  20.  
  21. The current version while these lines are written is 0.9.0. Encryption is
  22. plagued by legal problems of all kinds. For a discussion of these please
  23. read the documentation of SSLeay, which is available at
  24.  
  25.     http://www.psy.uq.edu.au/~ftp/Crypto/
  26.  
  27. To compile samba with SSL support, you must first compile and install SSLeay.
  28. SSLeay consists of a library (which can be linked to other applications like
  29. samba) and several utility programs needed for key generation, certification
  30. etc. SSLeay installs to /usr/local/ssl/ by default.
  31.  
  32.  
  33. Compiling samba with SSLeay
  34. ===========================
  35. 1. Get and install SSLeay. The rest of this documentation assumes that you
  36.    have installed it at the default location, which is /usr/local/ssl/.
  37.    I have used SSLeay 0.9.0, but samba will probably also work with other
  38.    versions (but not with versions older than 0.6).
  39. 2. Modify the Makefile. At the end of the configurable section you can find
  40.    the SSL definitions. You can find them quickly by searching for SSL_ROOT.
  41.    Unremark the definitions and modify SSL_ROOT if necessary.
  42. 3. Compile and install as usual.
  43.  
  44.  
  45. Configuring SSL in samba
  46. ========================
  47. Before you configure SSL, you should know the basics of cryptography and how
  48. SSL relates to all of this. A basic introduction can be found further down in
  49. this document. The following variables in the "[global]" section of the
  50. configuration file are used to configure SSL:
  51.  
  52. ssl                     = yes
  53.    This variable enables or disables the entire SSL mode. If it is set to
  54.    "no", the SSL enabled samba behaves exactly like the non-SSL samba. If set
  55.    to "yes", it depends on the variables "ssl hosts" and "ssl hosts resign"
  56.    whether an SSL connection will be required.
  57. ssl hosts               = 
  58. ssl hosts resign        = 192.168.
  59.    These two variables define whether samba will go into SSL mode or not. If
  60.    none of them is defined, samba will allow only SSL connections. If the
  61.    "ssl hosts" variable lists hosts (by IP-address, IP-address range, net
  62.    group or name), only these hosts will be forced into SSL mode. If the
  63.    "ssl hosts resign" variable lists hosts, only these hosts will NOT be
  64.    forced into SSL mode. The syntax for these two variables is the same as
  65.    for the "hosts allow" and "hosts deny" pair of variables, only that the
  66.    subject of the decision is different: It's not the access right but
  67.    whether SSL is used or not. See the man page of smb.conf (section about
  68.    "allow hosts") for details. The above example requires SSL connections
  69.    from all hosts outside the local net (which is 192.168.*.*).
  70. ssl CA certDir          = /usr/local/ssl/certs
  71.    This variable defines where to look up the Certification Autorities. The
  72.    given directory should contain one file for each CA that samba will trust.
  73.    The file name must be the hash value over the "Distinguished Name" of the
  74.    CA. How this directory is set up is explained later in this document. All
  75.    files within the directory that don't fit into this naming scheme are
  76.    ignored. You don't need this variable if you don't verify client
  77.    certificates.
  78. ssl CA certFile         = /usr/local/ssl/certs/trustedCAs.pem
  79.    This variable is a second way to define the trusted CAs. The certificates
  80.    of the trusted CAs are collected in one big file and this variable points
  81.    to the file. You will probably only use one of the two ways to define your
  82.    CAs. The first choice is preferable if you have many CAs or want to be
  83.    flexible, the second is perferable if you only have one CA and want to
  84.    keep things simple (you won't need to create the hashed file names). You
  85.    don't need this variable if you don't verify client certificates.
  86. ssl server cert         = /usr/local/ssl/certs/samba.pem
  87.    This is the file containing the server's certificate. The server _must_
  88.    have a certificate. The file may also contain the server's private key.
  89.    See later for how certificates and private keys are created.
  90. ssl server key          = /usr/local/ssl/private/samba.pem
  91.    This file contains the private key of the server. If this variable is not
  92.    defined, the key is looked up in the certificate file (it may be appended
  93.    to the certificate). The server _must_ have a private key and the
  94.    certificate _must_ match this private key.
  95. ssl client cert         = /usr/local/ssl/certs/smbclient.pem
  96.    The certificate in this file is used by smbclient if it exists. It's needed
  97.    if the server requires a client certificate.
  98. ssl client key          = /usr/local/ssl/private/smbclient.pem
  99.    This is the private key for smbclient. It's only needed if the client
  100.    should have a certificate.
  101. ssl require clientcert  = yes
  102.    If this variable is set to "yes", the server will not tolerate connections
  103.    from clients that don't have a valid certificate. The directory/file
  104.    given in "ssl CA certDir" and "ssl CA certFile" will be used to look up
  105.    the CAs that issued the client's certificate. If the certificate can't be
  106.    verified positively, the connection will be terminated.
  107.    If this variable is set to "no", clients don't need certificates. Contrary
  108.    to web applications you really _should_ require client certificates. In
  109.    the web environment the client's data is sensitive (credit card numbers)
  110.    and the server must prove to be trustworthy. In a file server environment
  111.    the server's data will be sensitive and the clients must prove to be
  112.    trustworthy.
  113. ssl require servercert  = yes
  114.    If this variable is set to "yes", the smbclient will request a certificate
  115.    from the server. Same as "ssl require clientcert" for the server.
  116. ssl ciphers             = ???
  117.    This variable defines the ciphers that should be offered during SSL
  118.    negotiation. You should not set this variable unless you know what you do.
  119. ssl version             = ssl2or3
  120.    This enumeration variable defines the versions of the SSL protocol that
  121.    will be used. "ssl2or3" allows dynamic negotiation of SSL v2 or v3, "ssl2"
  122.    results SSL v2, "ssl3" results in SSL v3 and "tls1" results in TLS v1. TLS
  123.    (Transport Layer Security) is the (proposed?) new standard for SSL. The
  124.    default value is "ssl2or3".
  125. ssl compatibility       = no
  126.    This variable defines whether SSLeay should be configured for bug
  127.    compatibility with other SSL implementations. This is probably not
  128.    desirable because currently no clients with SSL implementations other than
  129.    SSLeay exist.
  130.  
  131.  
  132. Running samba with SSLeay
  133. =========================
  134. Samba is started as usual. The daemon will ask for the private key's pass
  135. phrase before it goes to background if the private key has been encrypted.
  136. If you start smbd from inetd, this won't work. Therefore you must not encrypt
  137. your private key if you run smbd from inetd.
  138.  
  139. Windows clients will try to connect to the SSL enabled samba daemon and they
  140. will fail. This can fill your log with failed SSL negotiation messages. To
  141. avoid this, you can either not run nmbd (if all clients use DNS to look up
  142. the server), which will leave the Windows machine unaware of the server, or
  143. list all (local) Windows machines in the "ssl hosts resign" variable.
  144.  
  145.  
  146. About certificates
  147. ==================
  148. Secure samba servers will not be set up for public use as it is the case with
  149. secure web servers. Most installations will probably use it for distributed
  150. offices that use parts of the internet for their intranet, for access to a
  151. web server that's physically hosted by the provider or simply for teleworking.
  152. All these applications work with a known group of users that can easily agree
  153. on a certification authority. The CA can be operated by the company and the
  154. policy for issuing certificates can be determined by the company. If samba is
  155. configured to verify client certificates, it (currently) only verifies
  156. whether a valid certificate exists. It does not verify any of the data within
  157. the certificate (although it prints some of the data to the log file).
  158.  
  159.  
  160. Which clients are available that support SSL?
  161. =============================================
  162. Currently there are only smbclient which is part of the samba package and
  163. Sharity. Shariy versions newer than 0.14 in the beta branch and 1.01 in the
  164. main branch can be compiled with SSLeay. Sharity is a CIFS/SMB client
  165. implementation for Unix. It is a commercial product, but it is available in
  166. source code and the demo-mode allows access to the first three layers of the
  167. mounted directory hierarchy. Licenses for universities and students are free.
  168. Sharity is available at
  169.  
  170.     http://www.obdev.at/Products/Sharity.html
  171.  
  172.  
  173.  
  174. ###########################################################################
  175. Basics about Cryptography and SSL(eay)
  176. ###########################################################################
  177.  
  178. There are many good introductions to cryptography. I assume that the reader
  179. is familiar with the words "encryption", "digital signature" and RSA. If you
  180. don't know these terms, please read the cryptography FAQ part 6 and 7, which
  181. is posted to the usenet newsgroup sci.crypt. It is also available from
  182.  
  183.     ftp://rtfm.mit.edu/pub/usenet/news.answers/cryptography-faq
  184. and
  185.     http://www.cis.ohio-state.edu/hypertext/faq/usenet/cryptography-faq
  186.  
  187. I'll concentrate on the questions specific to SSL and samba here.
  188.  
  189.  
  190. What is a certificate?
  191. ======================
  192. A certificate is issued by an issuer, usually a "Certification Authority"
  193. (CA), who confirms something by issuing the certificate. The subject of this
  194. confirmation depends on the CA's policy. CAs for secure web servers (used for
  195. shopping malls etc.) usually only attest that the given public key belongs the
  196. the given domain name. Company-wide CAs might attest that you are an employee
  197. of the company, that you have permissions to use a server or whatever.
  198.  
  199.  
  200. What is an X.509 certificate technically?
  201. =========================================
  202. Technically, the certificate is a block of data signed by the certificate
  203. issuer (the CA). The relevant fields are:
  204.    - unique identifier (name) of the certificate issuer
  205.    - time range during that the certificate is valid
  206.    - unique identifier (name) of the certified subject
  207.    - public key of the certified subject
  208.    - the issuer's signature over all of the above
  209. If this certificate should be verified, the verifier must have a table of the
  210. names and public keys of trusted CAs. For simplicity, these tables are lists
  211. of certificates issued by the respective CAs for themselves (self-signed
  212. certificates).
  213.  
  214.  
  215. What are the implications of this certificate structure?
  216. ========================================================
  217.   - Because the certificate contains the subject's public key, the
  218.     certificate and the private key together are all that's needed to encrypt
  219.     and decrypt.
  220.   - To verify certificates, you need the certificates of all CAs you trust.
  221.   - The simplest form of a dummy-certificate is one that's signed by the
  222.     subject itself.
  223.   - A CA is needed. The client can't simply issue local certificates for
  224.     servers it trusts because the server determines which certificate it
  225.     presents.
  226.  
  227.  
  228.  
  229. ###########################################################################
  230. Setting up files and directories for SSLeay
  231. ###########################################################################
  232.  
  233. The first thing you should do is to change your PATH environment variable to
  234. include the bin directory of SSLeay. E.g.:
  235.  
  236.     PATH=$PATH:/usr/local/ssl/bin   
  237.  
  238. Then you should set up SSLeay's random number generator. The state of this
  239. random number generator is held in the file ".rnd" in your home directory. To
  240. set a reasonable random seed, you need random data. Create a random file with
  241.     
  242.     cat >/tmp/rfile.txt
  243.  
  244. Then type random keys on your keyboard for about one minute. Then type the
  245. EOF character (^D) to terminate input. You may also use your favorite editor
  246. to create the random file, of course. Now you can create a dummy key to
  247. initialize the random number generator:
  248.     
  249.     ssleay genrsa -rand /tmp/rfile.txt > /dev/null
  250.     rm -f /tmp/rfile.txt
  251.  
  252. Don't forget to delete the file /tmp/rfile.txt. It's more or less equivalent
  253. to your private key!
  254.  
  255.  
  256. How to create a keypair
  257. =======================
  258. This is done with 'genrsa' for RSA keys and 'gendsa' for DSA keys. For an RSA
  259. key with 512 bits which is written to the file "key.pem" type:
  260.  
  261.     ssleay genrsa -des3 512 > key.pem
  262.  
  263. You will be asked for a pass phrase to protect this key. If you don't want to
  264. protect your private key with a pass phrase, just omit the parameter "-des3".
  265. If you want a different key size, replace the parameter "512". You really
  266. should use a pass phrase.
  267.  
  268. If you want to remove the pass phrase from a key use:
  269.  
  270.     ssleay rsa -in key.pem -out newkey.pem
  271.  
  272. And to add or change a pass phrase:
  273.  
  274.     ssleay rsa -des3 -in key.pem -out newkey.pem
  275.  
  276.  
  277. How to create a dummy certificate
  278. =================================
  279. If you still have your keypair in the file "key.pem", the command
  280.  
  281.     ssleay req -new -x509 -key key.pem -out cert.pem
  282.  
  283. will write a self-signed dummy certificate to the file "cert.pem". This can
  284. be used for testing or if only encryption and no certification is needed.
  285. Please bear in mind that encryption without authentication (certification)
  286. can never be secure. It's open to (at least) "man-in-the-middle" attacks.
  287.  
  288.  
  289. How to create a certificate signing request
  290. ===========================================
  291. You must not simply send your keypair to the CA for signing because it
  292. contains the private key which _must_ be kept secret. A signing request
  293. consists of your public key and some additional information you want to have
  294. bound to that key by the certificate. If you operate a secure web server,
  295. this additional information will (among other things) contain the URL of
  296. your server in the field "Common Name". The certificate signing request is
  297. created from the keypair with the following command (assuming that the key
  298. pair is still in "key.pem"):
  299.  
  300.     ssleay req -new -key key.pem -out csr.pem
  301.  
  302. This command will ask you for the information which must be included in the
  303. certificate and will write the signing request to the file "csr.pem". This
  304. signing request is all the CA needs for signing, at least technically. Most
  305. CAs will demand bureaucratic material and money, too.
  306.  
  307.  
  308. How to set up a Certification Authority (CA)
  309. ============================================
  310. Being a certification authority requires a database that holds the CA's
  311. keypair, the CA's certificate, a list of all signed certificates and other
  312. information. This database is kept in a directory hierarchy below a
  313. configurable starting point. The starting point must be configured in the
  314. ssleay.conf file. This file is at /usr/local/ssl/lib/ssleay.conf if you have
  315. not changed the default installation path.
  316.  
  317. The first thing you should do is to edit this file according to your needs.
  318. Let's  assume that you want to hold the CA's database at the directory
  319. "/usr/local/ssl/CA". Change the variable "dir" in section "CA_default" to
  320. this path. You may also want to edit the default settings for some variables,
  321. but the values given should be OK. This path is also contained in the shell
  322. script CA.sh, which should be at "/usr/local/ssl/bin/CA.sh". Change the path
  323. in the shell script:
  324.  
  325.     CATOP=/usr/local/ssl/CA
  326.     CAKEY=./cakey.pem           # relative to $CATOP/
  327.     CACERT=./cacert.pem         # relative to $CATOP/private/
  328.  
  329. Then create the directory "/usr/local/ssl/CA" and make it writable for the
  330. user that operates the CA. You should also initialize SSLeay as CA user (set
  331. up the random number generator). Now you should call the shell script CA.sh
  332. to set up the initial database:
  333.  
  334.     CA.sh -newca
  335.  
  336. This command will ask you whether you want to use an existing certificate or
  337. create one. Just press enter to create a new key pair and certificate. You
  338. will be asked the usual questions for certificates: the country, state, city,
  339. "Common Name", etc. Enter the appropriate values for the CA. When CA.sh
  340. finishes, it has set up a bunch of directories and files. A CA must publish
  341. it's certificate, which is in the file "/usr/local/ssl/CA/cacert.pem".
  342.  
  343.  
  344. How to sign a certificate request
  345. =================================
  346. After setting up the CA stuff, you can start signing certificate requests.
  347. Make sure that the SSLeay utilities know where the configuration file is.
  348. The default is compiled in, if you don't use the default location, add the
  349. parameter "-config <cfg-file>". Make also sure that the configuration file
  350. contains the correct path to the CA database. If all this is set up properly,
  351. you can sign the request in the file "csr.pem" with the command:
  352.  
  353.     ssleay ca -policy policy_anything -days 365 -infiles csr.pem >cert.pem
  354.  
  355. The resulting certificate (and additional information) will be in "cert.pem".
  356. If you want the certificate to be valid for a period different from 365 days,
  357. simply change the "-days" parameter.
  358.  
  359.  
  360. How to install a new CA certificate
  361. ===================================
  362. Whereever a certificate must be checked, the CA's certificate must be
  363. available. Let's take the common case where the client verifies the server's
  364. certificate. The case where the server verfies the client's certificate works
  365. the same way. The client receives the server's certificate, which contains
  366. the "Distinguished Name" of the CA. To verify whether the signature in this
  367. certificate is OK, it must look up the public key of that CA. Therefore each
  368. client must hold a database of CAs, indexed by CA name. This database is best
  369. kept in a directory where each file contains the certificate of one CA and is
  370. named after the hashvalue (checksum) of the CA's name. This section describes
  371. how such a database is managed technically. Whether or not to install (and
  372. thereby trust) a CA is a totally different matter.
  373.  
  374. The client must know the directory of the CA database. This can be configured.
  375. There may also be a configuration option to set up a CA database file which
  376. contains all CA certs in one file. Let's assume that the CA database is kept
  377. in the directory "/usr/local/ssl/certs". The following example assumes that
  378. the CA's certificate is in the file "cacert.pem" and the CA is known as
  379. "myCA". To install the certificate, do the following:
  380.  
  381.     cp cacert.pem /usr/local/ssl/cers/myCA.pem
  382.     cd /usr/local/ssl/certs
  383.     ln -s myCA.pem `ssleay x509 -noout -hash < myCA.pem`.0
  384.  
  385. The last command creates a link from the hashed name to the real file.
  386.  
  387. From now on all certificates signed by the myCA authority will be accepted by
  388. clients that use the directory "/usr/local/ssl/certs/" as their CA certificate
  389. database.
  390.  
  391.  
  392.  
  393.